SST ShlWAPI GetAcceptLanguages Function

	(SST) ShlWAPI.pas Version 1.08

Developer Reference

(SST)ShlWAPI GetAcceptLanguages Function
Retrieves the ordered list of abbreviations for the preferred languages, as configured/defined in the Internet Properties/Options' Language Preferences (dialog).

Scope
Global (i.e. this function can be called/accessed from code in any unit that includes/uses (SST)ShlWAPI.pas).

Syntax
	function GetAcceptLanguages(psz : LPSTR; pcch : LPDWORD) : HRESULT;
	function GetAcceptLanguagesA(psz : LPSTR; pcch : LPDWORD) : HRESULT; function GetAcceptLanguagesW(psz : LPWSTR; pcch : LPDWORD) : HRESULT;

Parameters
psz [out]	A pointer to the buffer into which the function should write the NULL-terminated, ANSI or Unicode output string.
pcch [in/out]	Address of or pointer to a DWORD variable, that the calling function should set to the size of the buffer (including the terminating null-character), into which the output string is written. The function sets this variable to the number of characters actually written to the buffer when it returns.

Return Values
If the function succeeded in retrieving the requested information and writing it to the provided buffer, it returns S_OK (= 0). If the function fails it returns a COM-defined error code. Typically, this is $8007 0057 ("The parameter is incorrect").

Remarks
To determine the required buffer size, the function may be called with NIL as the first parameter. In this case, it will return the number of non-zero characters it will write to the buffer (i.e. the required buffer size, not includding the terminating null-character).
The documentation accompanying Ms SDK 6.1 contained statements that conflicted with the declaration in that SDK's header file (ShlWAPI.h). Specifically, it was documented as being supported as of ShlWAPI.dll version 5.0 under Windows 2000, but was declared as requiring IE >= "0x0603" (= _WIN32_IE_IE60SP2), the min. ShlWAPI.dll and Windows versions under which it is exported by name. However, the same article stated correctly that, under Windows versions that do not export the function by name, both the ANSI and Unicode version of the function can be accessed directly by means of their ordinals (14 & 15, respectively).

Remarks

To determine the required buffer size, the function may be called with NIL as the first parameter. In this case, it will return the number of non-zero characters it will write to the buffer (i.e. the required buffer size, not includding the terminating null-character).

The documentation accompanying Ms SDK 6.1 contained statements that conflicted with the declaration in that SDK's header file (ShlWAPI.h). Specifically, it was documented as being supported as of ShlWAPI.dll version 5.0 under Windows 2000, but was declared as requiring IE >= "0x0603" (= _WIN32_IE_IE60SP2), the min. ShlWAPI.dll and Windows versions under which it is exported by name. However, the same article stated correctly that, under Windows versions that do not export the function by name, both the ANSI and Unicode version of the function can be accessed directly by means of their ordinals (14 & 15, respectively).

Example
PROCEDURE TForm4.TestShlWAPIGetAcceptLanguages(Sender : TObject); VAR acceptedlangsbuf : ARRAY[0..128] OF CHAR; VAR bufsize : DWORD; VAR apiretval : HRESULT; VAR newinfoline : STRING; BEGIN FillChar(acceptedlangsbuf, Length(acceptedlangsbuf), #0); bufsize := 0; apiretval := 0; // = S_OK newinfoline := ''; bufsize := Length(acceptedlangsbuf); apiretval := GetAcceptLanguages(acceptedlangsbuf, @bufsize); IF apiretval = S_OK THEN newinfoline := 'GetAcceptLanguages returned : ' + acceptedlangsbuf ELSE newinfoline := 'returned error code : ' + IntToStr(apiretval) + ' (0x' + IntToHex(apiretval, 8) + ')'; Memo1.Lines.Add(newinfoline); Memo1.Lines.Add(''); END;
Fig. 2.1.2.3.8.1.0.1 If the Internet language preferences are configured as in the dialog shown above, the code example will produce the following output:
GetAcceptLanguages returned : en-US,de-DE;q=0.8,fr-FR;q=0.6,gsw-FR;q=0.4,pt-PT;q=0.2

Requirements
Unit:	Declared and imported in (SST)ShlWAPI.pas
Library:	(SST)ShlWAPI.dcu/(SST)ShlWAPI.obj
Unicode:	Implemented as ANSI (GetAcceptLanguages and GetAcceptLanguagesA) and Unicode (GetAcceptLanguagesW) functions.
Min. ShlWAPI.dll version according to MS SDK doc.:	5.0
Min. ShlWAPI.dll version based on SST research:	5.0
Min. OS version(s) according to Microsoft SDK doc.:	Windows 2000, Windows XP
Min. OS version(s) according to SST research.:	Windows 98 SE with Internet Explorer 5.0, Windows 2000

See Also


Windows APIs: GetAcceptLanguages.

Document/Contents version 1.00
Page/URI last updated on 07.12.2023

Suggestions and comments mail to:
webmaster@stoelzelsoftwaretech.com